home *** CD-ROM | disk | FTP | other *** search
/ Scene 96 / Scene 96 International Edition (Zyklop Software) (Disc 2) (1997).iso / misc / coding / midas060 / src / midasstr.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-01-16  |  12.1 KB  |  354 lines
  1. /*      midasstr.h
  2.  *
  3.  * MIDAS stream library
  4.  *
  5.  * $Id: midasstr.h,v 1.5 1997/01/16 19:31:53 pekangas Exp $
  6.  *
  7.  * Copyright 1996,1997 Housemarque Inc.
  8.  *
  9.  * This file is part of the MIDAS Sound System, and may only be
  10.  * used, modified and distributed under the terms of the MIDAS
  11.  * Sound System license, LICENSE.TXT. By continuing to use,
  12.  * modify or distribute this file you indicate that you have
  13.  * read the license and understand and accept it fully.
  14. */
  15.  
  16.  
  17. #ifndef __midasstr_h
  18. #define __midasstr_h
  19.  
  20.  
  21. /* Hack for Linux: (FIXME) */
  22. #ifdef __LINUX__
  23. #include <pthread.h>
  24. #endif
  25.  
  26. /****************************************************************************\
  27. *       enum strStreamMode
  28. *       ------------------
  29. * Description:  Stream playing mode
  30. \****************************************************************************/
  31.  
  32. enum strStreamMode
  33. {
  34.     strStreamPlayFile = 1,
  35.     strStreamCallback,
  36.     strStreamPoll
  37. };
  38.  
  39.  
  40. /****************************************************************************\
  41. *       struct strStream
  42. *       ----------------
  43. * Description:  Stream playing structure
  44. \****************************************************************************/
  45.  
  46. typedef struct _strStream
  47. {
  48.     unsigned    sdChannel;              /* channel number for the stream */
  49.     uchar       *buffer;                /* pointer to stream buffer */
  50.     unsigned    bufferSamples;          /* buffer length in samples */
  51.     unsigned    bufferBytes;            /* buffer length in bytes */
  52.     unsigned    bufferWritePos;         /* buffer write position */
  53.     uchar       *fileBuffer;            /* file reading buffer */
  54.     unsigned    fileBufferBytes;        /* file reading buffer size */
  55.     unsigned    sampleSize;             /* size of one sample in bytes */
  56.     int         streamMode;             /* see enum strStreamMode */
  57.     fileHandle  f;                      /* stream file handle */
  58.     ulong       fileLength;             /* stream file length in bytes */
  59.     ulong       fileLeft;               /* number of bytes left in file */
  60.     int         loop;                   /* 1 if the stream loops */
  61.     volatile int threadExitFlag;        /* thread exit flag */
  62.     unsigned    threadDelay;            /* delay between polling in thread */
  63.     void (CALLING *callback)(uchar *buffer, struct _strStream *stream);
  64. #ifdef __LINUX__
  65.     pthread_t   playerThread;           /* player thread */
  66. #endif
  67.                                         /* stream playing callback */
  68.     uchar       bufferClearVal;         /* the value that should be used to
  69.                                            clear the buffer */
  70.     uchar       filler[3];
  71. } strStream;
  72.  
  73.  
  74.  
  75. #ifdef __cplusplus
  76. extern "C" {
  77. #endif
  78.  
  79.  
  80.  
  81. /****************************************************************************\
  82. *
  83. * Function:     int strInit(SoundDevice *SD)
  84. *
  85. * Description:  Initializes the stream library
  86. *
  87. * Input:        SoundDevice *SD         Pointer to the Sound Device that will
  88. *                                       be used for playing the streams
  89. *
  90. * Returns:      MIDAS error code
  91. *
  92. \****************************************************************************/
  93.  
  94. int CALLING strInit(SoundDevice *SD);
  95.  
  96.  
  97.  
  98.  
  99. /****************************************************************************\
  100. *
  101. * Function:     int strClose(void)
  102. *
  103. * Description:  Uninitializes the stream library
  104. *
  105. * Returns:      MIDAS error code
  106. *
  107. \****************************************************************************/
  108.  
  109. int CALLING strClose(void);
  110.  
  111.  
  112.  
  113. /****************************************************************************\
  114. *
  115. * Function:     int strPlayStreamFile(unsigned channel, char *fileName,
  116. *                   unsigned sampleType, ulong sampleRate,
  117. *                   unsigned bufferLength, int loop, strStream **stream)
  118. *
  119. * Description:  Starts playing a digital sound stream from a file. Creates a
  120. *               new thread that will take care of reading the file and feeding
  121. *               it to the stream buffer
  122. *
  123. * Input:        unsigned channel        channel number for the stream
  124. *               char *fileName          stream file name
  125. *               unsigned sampleType     stream sample type
  126. *               ulong sampleRate        sampling rate
  127. *               unsigned bufferLength   stream buffer length in milliseconds
  128. *               int loop                1 if the stream should be looped,
  129. *                                       0 if not
  130. *               strStream **stream      pointer to stream state pointer
  131. *
  132. * Returns:      MIDAS error code. Pointer to the stream state structure will
  133. *               be written to *stream
  134. *
  135. \****************************************************************************/
  136.  
  137. int CALLING strPlayStreamFile(unsigned channel, char *fileName,
  138.     unsigned sampleType, ulong sampleRate, unsigned bufferLength, int loop,
  139.     strStream **stream);
  140.  
  141.  
  142.  
  143.  
  144. /****************************************************************************\
  145. *
  146. * Function:     int strPlayStreamPolling(unsigned channel,
  147. *                   unsigned sampleType, ulong sampleRate,
  148. *                   unsigned bufferLength, strStream **stream)
  149. *
  150. * Description:  Starts playing a stream in polling mode. Use
  151. *               strFeedStreamData() to feed the stream data to the player
  152. *
  153. * Input:        unsigned channel        channel number for the stream
  154. *               unsigned sampleType     stream sample type
  155. *               ulong sampleRate        stream sampling rate
  156. *               unsigned bufferLength   stream buffer length in milliseconds
  157. *               strStream **stream      pointer to stream state pointer
  158. *
  159. * Returns:      MIDAS error code. Pointer to the stream state structure will
  160. *               be written to *stream
  161. *
  162. \****************************************************************************/
  163.  
  164. int CALLING strPlayStreamPolling(unsigned channel, unsigned sampleType,
  165.     ulong sampleRate, unsigned bufferLength, strStream **stream);
  166.  
  167.  
  168.  
  169. /****************************************************************************\
  170. *
  171. * Function:     int strPlayStreamCallback(unsigned sampleType,
  172. *                  ulong sampleRate, unsigned bufferBytes,
  173. *                  void (CALLING *callback)(uchar *buffer, strStream *stream))
  174. *
  175. * Description:  Starts playing a stream with a callback.
  176. *
  177. * Input:        unsigned sampleType     stream sample type
  178. *               ulong sampleRate        stream sampling rate
  179. *               unsigned bufferBytes    stream buffer size _IN BYTES_
  180. *               ... *callback           stream player callback
  181. *               strStream **stream      pointer to stream state pointer
  182. *
  183. * Returns:      MIDAS error code. Pointer to the stream state structure will
  184. *               be written to *stream
  185. *
  186. * Notes:        The callback function will be called each time the whole
  187. *               stream buffer needs to be filled. It receives as an argument
  188. *               a pointer to the buffer, and the stream state pointer.
  189. *
  190. *               The function will be called from inside the mixing routine,
  191. *               so it should return relatively rapidly - do not use this
  192. *               function for, for example, loading data from disc.
  193. *
  194. \****************************************************************************/
  195.  
  196. int CALLING strPlayStreamCallback(unsigned sampleType, ulong sampleRate,
  197.     unsigned bufferBytes,
  198.     void (CALLING *callback)(uchar *buffer, strStream *stream));
  199.  
  200.  
  201.  
  202.  
  203. /****************************************************************************\
  204. *
  205. * Function:     int strStopStream(strStream *stream)
  206. *
  207. * Description:  Stops playing a stream. This function will also destroy the
  208. *               playback thread for stream file playback.
  209. *
  210. * Input:        strStream *stream       stream state pointer for the stream
  211. *
  212. * Returns:      MIDAS error code.
  213. *
  214. \****************************************************************************/
  215.  
  216. int CALLING strStopStream(strStream *stream);
  217.  
  218.  
  219.  
  220.  
  221. /****************************************************************************\
  222. *
  223. * Function:     int strFeedStreamData(strStream *stream, uchar *data,
  224. *                   unsigned numBytes, int feedAll, unsigned *numFed)
  225. *
  226. * Description:  Feeds sample data to a stream that is being played in polling
  227. *               mode.
  228. *
  229. * Input:        strStream *stream       stream state pointer from
  230. *                                       strPlayStreamPolling()
  231. *               uchar *data             pointer to stream data
  232. *               unsigned numBytes       number of bytes of data to feed. Note!
  233. *                                       This must be a multiple of the stream
  234. *                                       sample size
  235. *               int feedAll             1 if all data should be fed in all
  236. *                                       circumstances. The function will block
  237. *                                       the current thread if this flag is 1
  238. *                                       until all data is fed.
  239. *               unsigned *numFed        pointer to a variable that will
  240. *                                       contain the number of bytes actually
  241. *                                       fed
  242. *
  243. * Returns:      MIDAS error code. The number of bytes of data actually fed is
  244. *               written to *numFed.
  245. *
  246. \****************************************************************************/
  247.  
  248. int CALLING strFeedStreamData(strStream *stream, uchar *data,
  249.     unsigned numBytes, int feedAll, unsigned *numFed);
  250.  
  251.  
  252.  
  253.  
  254. /****************************************************************************\
  255. *
  256. * Function:     int strSetStreamRate(strStream *stream, ulong sampleRate)
  257. *
  258. * Description:  Changes the sampling rate for a stream
  259. *
  260. * Input:        strStream *stream       stream state pointer
  261. *               ulong sampleRate        new sampling rate in Hz
  262. *
  263. * Returns:      MIDAS error code
  264. *
  265. \****************************************************************************/
  266.  
  267. int CALLING strSetStreamRate(strStream *stream, ulong sampleRate);
  268.  
  269.  
  270.  
  271.  
  272. /****************************************************************************\
  273. *
  274. * Function:     int strSetStreamVolume(strStream *stream, unsigned volume)
  275. *
  276. * Description:  Changes the playback volume for a stream (the default is 64).
  277. *
  278. * Input:        strStream *stream       stream state pointer
  279. *               unsigned volume         new volume (0-64)
  280. *
  281. * Returns:      MIDAS error code.
  282. *
  283. \****************************************************************************/
  284.  
  285. int CALLING strSetStreamVolume(strStream *stream, unsigned volume);
  286.  
  287.  
  288.  
  289.  
  290. /****************************************************************************\
  291. *
  292. * Function:     int strSetStreamPanning(strStream *stream, int panning)
  293. *
  294. * Description:  Changes the panning for a stream (the default is middle).
  295. *
  296. * Input:        strStream *stream       stream state pointer
  297. *               int panning             new panning position
  298. *
  299. * Returns:      MIDAS error code.
  300. *
  301. \****************************************************************************/
  302.  
  303. int CALLING strSetStreamPanning(strStream *stream, int panning);
  304.  
  305.  
  306.  
  307. /****************************************************************************\
  308. *
  309. * Function:     int strIsStreamFinished(strStream *stream, int *finished)
  310. *
  311. * Description:  Checks whether a given stream has reached the end of the
  312. *               stream file or not. Only applies to streams played from a
  313. *               file.
  314. *
  315. * Input:        strStream *stream       stream state pointer
  316. *               int *finished           pointer to result variable
  317. *
  318. * Returns:      MIDAS error code. If the stream is finished, 1 will be written
  319. *               to *finished, otherwise *finished will contain 0.
  320. *
  321. \****************************************************************************/
  322.  
  323. int CALLING strIsStreamFinished(strStream *stream, int *finished);
  324.  
  325.  
  326.  
  327.  
  328. #ifdef __cplusplus
  329. }
  330. #endif
  331.  
  332.  
  333. #endif      /* #ifdef __midasstr_h */
  334.  
  335.  
  336. /*
  337.  * $Log: midasstr.h,v $
  338.  * Revision 1.5  1997/01/16 19:31:53  pekangas
  339.  * Fixed to compile with Linux GCC (but do they work?)
  340.  *
  341.  * Revision 1.4  1997/01/16 18:41:59  pekangas
  342.  * Changed copyright messages to Housemarque
  343.  *
  344.  * Revision 1.3  1997/01/16 18:25:08  pekangas
  345.  * Implemented strSetStreamRate, strSetStreamVolume and strSetStreamPanning
  346.  *
  347.  * Revision 1.2  1996/09/28 06:39:46  jpaana
  348.  * Converted from CR/LF and fixed some typos
  349.  *
  350.  * Revision 1.1  1996/09/22 23:17:48  pekangas
  351.  * Initial revision
  352.  *
  353. */
  354.